/**
 * 
 */
/**
 * <h2>XML Implementation of the Blueprint Design Pattern</h2>
 * 
 * <p>
 * This implementation of the blueprint design pattern relies on a separation of
 * the blueprint pattern element definitions and the Java representation of the
 * objects that the blueprint pattern elements describe. This package contains
 * the utility classes and methods required to read and write
 * XML-file-representations of blueprint pattern elements as well as
 * POJO-representations of those XML files (XMLBeans). The binding of XML file
 * definitions to POJOs in this package is achieved through the implementation
 * of the Java Architecture for XML Binding (JAXB).
 * </p>
 * 
 * <h3>XML File Structure</h3>
 * 
 * <p>
 * The motivation behind using XML as a language for blueprint definitions is
 * based on two important factors:
 * <ol>
 * <li>Java has an excellent XML-binding architecture in the form of JAXB</li>
 * <li>The XML file structure is well-suited to dynamically bind properties to
 * script-based instruction sets</li>
 * </ol>
 * The structure of the XML files associated with the blueprint design pattern
 * needs to be flexible enough to support variable properties and inter-file
 * scripting dependencies, but also needs to be defined by a strict structure in
 * order to bind individual Java classes to specific types of XML files. A
 * hierarchy of JAXB-compliant classes has been defined in this package that is
 * capable of handling this responsibility.
 * </p>
 * 
 * <p>
 * <ol>
 * <li>
 * <h4>Blueprint</h4>
 * <p>
 * The {@link Blueprint} class is the basic unit of the blueprint design pattern
 * and is defined by three components: its unique name, its property
 * definitions, and its encapsulating domains. The blueprint's unique name is
 * declared with a <code>name</code> tag, and the value will be interpreted as a
 * String object. For the blueprint's property definitions, an encapsulating
 * <code>propertyList</code> tag is used, inside of which an arbitrary number of
 * properties can be declared. Similarly, the blueprint's list of encapsulating
 * domains is declared by a <code>domainSet</code> tag, inside of which any
 * number of <code>domain</code> tags can be declared. The value of each
 * <code>domain</code> tag will be interpreted as a String object.
 * </p>
 * </li>
 * <li>
 * <h4>Modifier</h4>
 * <p>
 * The {@link Modifier} class is the incremental unit of the blueprint design
 * pattern and is defined by the same three components as the Blueprint class:
 * its unique name, its property definitions, and its encapsulating domains. The
 * modifier's unique name is declared with a <code>name</code> tag, and the
 * value will be interpreted as a String object. For the modifier's property
 * definitions, an encapsulating <code>propertyList</code> tag is used, inside
 * of which an arbitrary number of properties can be declared. Similarly, the
 * modifier's list of encapsulating domains is declared by a
 * <code>domainSet</code> tag, inside of which any number of <code>domain</code>
 * tags can be declared. The value of each <code>domain</code> tag will be
 * interpreted as a String object.
 * </p>
 * </li>
 * <li>
 * <h4>Factory</h4>
 * <p>
 * The {@link Factory} class is the associative unit of the blueprint design
 * pattern and is defined by three components as well: its unique name, its
 * blueprint "seed," and its list of modifiers. The factory's unique name is
 * declared with a <code>name</code> tag, and the value will be interpreted as a
 * String object. The factory's blueprint is declared with a
 * <code>blueprint</code> tag, and will be interpreted as a String. This is an
 * important distinction, because a Factory object contains no direct references
 * to either Blueprint objects or, as we will see, Modifier objects. Instead,
 * the blueprint and modifier fields of the Factory class are meant to contain
 * the unique identifying names of the blueprints and modifiers in question.
 * This is to prevent endless recursion during XML marshaling, as the blueprint
 * design pattern does not have any intrinsic recursion protection. Finally, the
 * factory's list of modifiers is declared by a <code>modifierList</code> tag,
 * inside of which an arbitrary number of <code>modifier</code> tags can be
 * declared. As with the <code>blueprint</code> tag, the value of each
 * <code>modifier</code> tag will be interpreted as a String object.
 * </p>
 * </li>
 * <li>
 * <h4>Property</h4>
 * <p>
 * The {@link Property} class is the backbone of the XML implementation of the
 * blueprint design pattern. Though it is very simple in design, it is powerful
 * in its flexibility. Each property is defined by two components: its type and
 * its value. The property's type is declared by the <code>type</code> tag, and
 * its value will be interpreted as a String object. A property's type is
 * expected to be used in inter-file scripting references, which is a very
 * powerful concept. For example, a modifier might have a property of type
 * "data," and the blueprint it modifies might have a property of the same type.
 * If the implementing scripting language supports it, the modifier could
 * reference the blueprint's "data" property and manipulate it in its own "data"
 * property. This concept can be extended, but the details of that extension are
 * covered in the {@link com.zastoupil.pgc.blueprint_pattern.xml.compile}
 * package. The other component of the Property class is the value, declared by
 * the <code>value</code> tag. This associates an expression in a predetermined
 * scripting language with the type declared by the <code>type</code> tag.
 * Again, the details on how the <code>value</code> tag's value are are
 * interpreted can be found in the
 * {@link com.zastoupil.pgc.blueprint_pattern.xml.compile} package.
 * </p>
 * </li>
 * </ol>
 * </p>
 * 
 * <h3>XML Configuration</h3>
 * 
 * <p>
 * In order for the XML-to-Java binding to maintain its structure, a set of
 * configurable options is stored in the {@link XMLConfig} class and in the
 * "xmlconfig.xml" XML file. That file, as well as all other configuration
 * files, can be found in the "/config" directory on the library class path. The
 * main configurable options are the directory paths for the blueprint,
 * modifier, and factory XML files, as well as the suffixes associated with
 * those files. In the absence of a predefined XML config file, any request for
 * one from the {@link XMLConfigReader} class will trigger the generation of a
 * default config file.
 * </p>
 * 
 * <p>
 * While the directories that store the blueprint, modifier, and factory XML
 * files do not need to be separate, it is important to note that file suffixes
 * should be unique for each class. This is because the marshaling and
 * unmarshaling utility methods in the {@link JAXBUtils} class (i.e.,
 * {@link JAXBUtils#marshal(Object)} and {@link JAXBUtils#unmarshal(String)})
 * depend upon the file suffixes being distinct.
 * </p>
 * 
 * @author Peter Zastoupil
 * 
 */
package com.zastoupil.pgc.blueprint_pattern.xml;
